package com.naiterui.common.repository.core;

import java.io.Serializable;
import java.util.List;

/**
 * 定义持久层通用的CRUD公共方法
 * 在不同的数据库间这些方法应该是通用的
 * 对于保存和更新的语义进行了明确限定
 * 不允许出现保存/更新的操作
 *
 * @author zhouyanxin
 * @since 1.0.0
 */
public interface BaseOperations<T, ID extends Serializable> {

    /**
     * Persist上下文中根据对象标识获取实体域对象
     * 其行为与findOne方法完全一致，
     * 封装的目的是为了贴近使用习惯
     * BaseOperations.get()
     *
     * @param id
     *
     * @return
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    T get(ID id);

    /**
     * 持久化对象
     * Spring-data-jpa中提供的Save方法是同时兼容插入与更新操作的，
     * 为了避免在实际使用中可以混淆两种情况，实现上进行了分离
     * 没有采用persist或insert作为方法命名是为了贴近使用习惯
     * BaseOperations.save()
     *
     * @param entities
     *
     * @return
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    <S extends T> S save(S entity);

    /**
     * 更新对象
     * Spring-data-jpa中提供的Save方法是同时兼容插入与更新操作的，
     * 为了避免在实际使用中可以混淆两种情况，实现上进行了分离
     * 没有采用merge或save作为方法命名是为了贴近使用习惯
     * BaseOperations.update()
     *
     * @param s
     *
     * @return
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    <S extends T> S update(S s);

    /**
     * 删除对象
     * BaseOperations.remove()
     *
     * @param s
     *
     * @Author zhouyanxin
     * @Date 2018年5月2日
     * @since 1.0.0
     */
    <S extends T> void remove(S s);

    /**
     * 根据ID进行删除
     * BaseOperations.removeById()
     *
     * @param id
     *
     * @Author zhouyanxin
     * @Date 2018年5月2日
     * @since 1.0.0
     */
    void removeById(ID id);

    /**
     * 批量保存实体对象
     * 会对给定的对象集合执行检查操作
     * 要求所有对象必须是游离状态
     * BaseOperations.save()
     *
     * @param entities
     *
     * @return
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    <S extends T> List<S> save(Iterable<S> entities);

    /**
     * 批量更新实体对象
     * 会对给定的对象集合执行检查操作
     * 要求所有对象必须是持久化状态
     * BaseOperations.update()
     *
     * @param entities
     *
     * @return
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    <S extends T> List<S> update(Iterable<S> entities);

    /**
     * 批量删除对象
     * BaseOperations.remove()
     *
     * @param entities
     *
     * @Author zhouyanxin
     * @Date 2017年11月18日
     * @since 1.0.0
     */
    void remove(List<T> entities);
}
